docs: schema governance tooling#2319
Conversation
|
@sarahxsanders is attempting to deploy a commit to the The GraphQL Foundation Team on Vercel. A member of the Team first needs to authorize it. |
|
@sarahxsanders were you looking into feedback already or should we wait a bit until this PR is not a draft? |
|
this one is ready too! @martinbonnin |
martinbonnin
left a comment
martinbonnin
left a comment
There was a problem hiding this comment.
A few comments. Nothing blocking. Thanks for looking into this ❤️
| performance: "", | ||
| security: "", | ||
| federation: "", | ||
| "debug-errors": "Common GraphQL over HTTP Errors", |
There was a problem hiding this comment.
This seems to be causing an error in CI: https://github.com/graphql/graphql.github.io/actions/runs/21336468897/job/61409128562?pr=2319
|
|
||
| ## Set up a schema registry | ||
|
|
||
| A schema registry stores and versions your GraphQL schemas, acting as the source of truth for what's deployed. Without a registry, teams often discover breaking changes only after deployment, when clients start failing. A registry enables you to compare proposed changes against production schemas before merge, track which schema version each environment runs, and maintain an audit trail of who changed what and when. |
There was a problem hiding this comment.
I'd stay clear of "source of truth" as the deployment is the source of truth at the end of the day.
| A schema registry stores and versions your GraphQL schemas, acting as the source of truth for what's deployed. Without a registry, teams often discover breaking changes only after deployment, when clients start failing. A registry enables you to compare proposed changes against production schemas before merge, track which schema version each environment runs, and maintain an audit trail of who changed what and when. | |
| A schema registry stores and versions your GraphQL schemas. Without a registry, teams often discover breaking changes only after deployment, when clients start failing. A registry enables you to compare proposed changes against production schemas before merge, track which schema version each environment runs, and maintain an audit trail of who changed what and when. |
| - **Hosted services** provide managed infrastructure with built-in features like schema composition for federation, usage analytics, and breaking change detection. They work well for teams that want to move fast without managing infrastructure. Consider data residency requirements and per-operation pricing at scale. | ||
| - **Self-hosted options** give you full control over data and costs. You'll need to handle deployment, scaling, and maintenance, but you avoid vendor lock-in and can customize behavior. This works well for organizations with strict compliance requirements or existing infrastructure expertise. | ||
| - **Lightweight approaches** work for smaller teams: store schemas in Git with validation in CI, use a shared S3 bucket with versioned objects, or build a simple API that stores schemas in your existing database. These approaches lack advanced features but may be all you need to start. |
There was a problem hiding this comment.
Love that breakdown 👍
|
|
||
| This example posts the schema to a registry with version metadata. | ||
|
|
||
| Add publication as a deployment step after successful builds, include metadata like git commit and author, and fail deployments if publication fails. |
There was a problem hiding this comment.
I tend to include the deployment in the "build" process. Maybe it's just a me thing but I would err on the side of explicit:
| Add publication as a deployment step after successful builds, include metadata like git commit and author, and fail deployments if publication fails. | |
| Add publication as a deployment step after successful builds but before deployment. Include metadata like git commit and author, and fail deployments if publication fails. |
|
|
||
| ## Automate validation in CI/CD | ||
|
|
||
| Schema validation catches problems before they reach production. The `graphql` package provides `findBreakingChanges` and `findDangerousChanges` functions that compare two schemas and return lists of differences. |
There was a problem hiding this comment.
TIL about findBreakingChanges.
Not related to this PR but would be really cool to have published API docs for graphql-js that we could link here.
|
|
||
| This example compares schemas and fails the build when breaking changes appear. | ||
|
|
||
| For approved breaking changes, like removing a deprecated field after migration, most teams use one of these approaches: |
| run: npm ci | ||
|
|
||
| - name: Validate schema syntax | ||
| run: npx graphql-inspector validate ./schema/*.graphql |
There was a problem hiding this comment.
Are we OK mentioning vendor tools on graphql.org? (same for @apollo/composition a few lines below)
| ## Generate reference documentation automatically | ||
|
|
||
| GraphQL's introspection makes documentation generation straightforward. Since your schema contains type names, field names, arguments, and descriptions, tools can generate complete API reference docs with litte manual effort. | ||
|
|
||
| The key to making GraphQL documentation effective is to make documentation generation automatic. Run it in CI after schema changes merge, and publish to wherever your developers look for docs. |
There was a problem hiding this comment.
I would expect this to be done by the registry automagically be having an explorer. Since the registry knows the schema, no need to do custome documentation generation.
| ### Alert on deprecated field usage | ||
| When clients continue using deprecated fields as the removal deadline approaches, send notifications to the responsible teams. |
There was a problem hiding this comment.
I'm curious how much that works in practice. The change is notified through the schema using @deprecated already. Adding another layer of automatic notification feels like duplication of effort.
I get that nudging colleagues is sometimes necessary but if it's an automatic email/notification and the client dev already ignored the @deprecated, there's a very high change they will ignore the notification similarly.
| ## Plan for rollbacks | ||
| Even with thorough validation, problematic schema changes occasionally reach production. Prepare rollback procedures before you need them. |
There was a problem hiding this comment.
Mixed feelings about this one. I've been telling some users to always fix "onwards".
I mostly consider my API like a database. Some people rely on it and once something reached production, it always go one direction.
2 participants
Description
adds a new governance tooling and automation page to the Learn section under a new "Schema Governance" category: